home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / pascal / xlibpas2.zip / XBM2.DOC < prev    next >
Text File  |  1994-06-12  |  20KB  |  438 lines
  1. ╔═══════════════════════════════════════════════════════════════════════════╗
  2. ║                                                                           ║
  3. ║        XLIB v2.0 - Graphics Library for Borland/Turbo Pascal 7.0          ║
  4. ║                                                                           ║
  5. ║               Tristan Tarrant - tristant@cogs.susx.ac.uk                  ║
  6. ║                                                                           ║
  7. ╠═══════════════════════════════════════════════════════════════════════════╣
  8. ║                                                                           ║
  9. ║                                 Credits                                   ║
  10. ║                                                                           ║
  11. ║                             Themie Gouthas                                ║
  12. ║                                                                           ║
  13. ║                            Matthew MacKenzie                              ║
  14. ║                                                                           ║
  15. ║                             Tore Bastiansen                               ║
  16. ║                                                                           ║
  17. ║                                 Andy Tam                                  ║
  18. ║                                                                           ║
  19. ║                               Douglas Webb                                ║
  20. ║                                                                           ║
  21. ║                              John  Schlagel                               ║
  22. ║                                                                           ║
  23. ╠═══════════════════════════════════════════════════════════════════════════╣
  24. ║                                                                           ║
  25. ║           I informally reserve all rights to the code in XLIB             ║
  26. ║       Rights to contributed code is also assumed to be reserved by        ║
  27. ║                          the original authors.                            ║
  28. ║                                                                           ║
  29. ╚═══════════════════════════════════════════════════════════════════════════╝
  30.  
  31. ╔═══════════════════════════════════════════════════════════════════════════╗
  32. ║ DISCLAIMER                                                                ║
  33. ╚═══════════════════════════════════════════════════════════════════════════╝
  34.  
  35.   This library is distributed AS IS. The author/s specifically disclaim any
  36.   responsibility for any loss of profit or any incidental, consequential or
  37.   other damages.
  38.  
  39. ╔═══════════════════════════════════════════════════════════════════════════╗
  40. ║ XBM2 : EXPORTED PROCEDURES AND FUNCTIONS                                  ║
  41. ╚═══════════════════════════════════════════════════════════════════════════╝
  42.  
  43.   This unit implements a set of functions to operate on bitmaps. XLIB2 uses
  44.   three different kinds of bitmaps :
  45.     Planar Bitmaps (PBMs),
  46.     Video Bitmaps   (VBMs),
  47.     Compiled Bitmaps (CBMs).
  48.  
  49. ╔═══════════════════════════════════════════════════════════════════════════╗
  50. ║ PBMs : EXPORTED PROCEDURES AND FUNCTIONS                                  ║
  51. ╚═══════════════════════════════════════════════════════════════════════════╝
  52.  
  53.   PBMs as used by these functions have the following structure:
  54.  
  55.     byte 0                 The bitmap width in bytes (4 pixel groups) range 1..255
  56.     byte 1                 The bitmap height in rows range 1..255
  57.     byte 2..n1             The plane 0 pixels width*height bytes
  58.     byte n1..n2            The plane 1 pixels width*height bytes
  59.     byte n2..n3            The plane 2 pixels width*height bytes
  60.     byte n3..n4            The plane 3 pixels width*height bytes
  61.  
  62.   These functions provide the fastest possible bitmap blts from system ram
  63.   to video and further, the single bitmap is applicable to all pixel
  64.   alignments. The masked functions do not need separate masks since all non
  65.   zero pixels are considered to be masking pixels, hence if a pixel is 0 the
  66.   corresponding screen destination pixel is left unchanged.
  67.  
  68.  
  69.   xputmaskedpbm
  70.   -------------
  71.  
  72.   Procedure xputmaskedpbm( X, Y, ScrnOffs : word; var Bitmap);
  73.  
  74.   Mask write a planar bitmap from system ram to video ram. All zero source
  75.   bitmap bytes indicate destination byte to be left unchanged.
  76.  
  77.   Source Bitmap structure:
  78.  
  79.   Width:byte, Height:byte, Bitmap data (plane 0)...Bitmap data (plane 1)..,
  80.   Bitmap data (plane 2)..,Bitmap data (plane 3)..
  81.  
  82.   NOTE: width is in bytes ie lots of 4 pixels
  83.  
  84.   LIMITATIONS: No clipping is supported
  85.            Only supports bitmaps with widths which are a multiple of
  86.            4 pixels
  87.  
  88.   xputpbm
  89.   -------
  90.  
  91.   Procedure xputpbm( X, Y, ScrnOffs : word; var Bitmap );
  92.  
  93.   Write a planar bitmap from system ram to video ram.
  94.  
  95.   Source Bitmap structure:
  96.  
  97.   Width:byte, Height:byte, Bitmap data (plane 0)...Bitmap data (plane 1)..,
  98.   Bitmap data (plane 2)..,Bitmap data (plane 3)..
  99.  
  100.   NOTE: width is in bytes ie lots of 4 pixels
  101.  
  102.   LIMITATIONS: No clipping is supported
  103.            Only supports bitmaps with widths which are a multiple of
  104.            4 pixels
  105.  
  106.   xgetpbm
  107.   -------
  108.  
  109.   Procedure xgetpbm( X, Y : word; Bw, Bh : byte; ScrnOffs : word;
  110.         var Bitmap );
  111.  
  112.   Read a planar bitmap to system ram from video ram.
  113.  
  114.   Source Bitmap structure:
  115.  
  116.   Width:byte, Height:byte, Bitmap data (plane 0)...Bitmap data (plane 1)..,
  117.   Bitmap data (plane 2)..,Bitmap data (plane 3)..
  118.  
  119.   NOTE: width is in bytes ie lots of 4 pixels
  120.  
  121.   LIMITATIONS: No clipping is supported
  122.            Only supports bitmaps with widths which are a multiple of
  123.            4 pixels
  124.  
  125.  
  126.  
  127.   A similar set of functions have been implemented to operate on planar
  128.   bitmaps but incorporating clipping to a user defined
  129.   clipping rectangle (which is set by xsetcliprect )
  130.  
  131.   There are three variations of the normal functions in this unit
  132.   identified by the three function name extensions: clipx, clipy clipxy.
  133.   Because speed is critical in games programming you do not want to be
  134.   checking for clipping if not necessary thus for sprites that move only
  135.   horizontally you would use the clipx version of the put function,
  136.   for sprites that move vertically you would use the clipy version and for
  137.   sprites that move both directions you would use the clipxy version.
  138.   Keep in mind also that the clipping components of these functions assume
  139.   that the clipping rectangle is equal to or larger than the size of the
  140.   bitmap ie. if a bitmap is top clipped, it is assumed that the bitmap's
  141.   bottom is not also clipped. Similarly with horizontal clipping.
  142.   Note: performance in decreasing order is as follows.
  143.   clipy,clipx,clipxy with masked puts being slower than unmasked puts
  144.  
  145.   Horizontal clipping is performed to byte boundaries (4 pixels) rather than
  146.   pixels. This allows for the fastest implementation of the functions. It is
  147.   not such a handicap because for one, your screen width a multiple of 4
  148.   pixels wide and  for most purposes it is the screen edges that form the
  149.   clipping rectangle.
  150.  
  151.   Following is an example of setting a clipping rectangle to the logical
  152.   screen edges:
  153.  
  154.   xsetcliprect(0,0,ScrnLogicalByteWidth,ScrnLogicalHeight)
  155.  
  156.   NOTE: the functions now return a value;
  157.     1 if clipped image is fully clipped (ie no portion of it
  158.     appears on the screen) otherwise it returns 0
  159.  
  160.  
  161.   xputpbmclipx
  162.   ------------
  163.   xputpbmclipy
  164.   ------------
  165.   xputpbmclipxy
  166.   -------------
  167.   xputmaskedpbmclipx
  168.   ------------------
  169.   xputmaskedpbmclipy
  170.   ------------------
  171.   xputmaskedpbmclipxy
  172.   -------------------
  173.  
  174.   For a detailed description of parameters etc. see equivalent functions
  175.   xputpbm, xputmaskedpbm
  176.  
  177. ╔═══════════════════════════════════════════════════════════════════════════╗
  178. ║ CBMs : EXPORTED PROCEDURES AND FUNCTIONS                                  ║
  179. ╚═══════════════════════════════════════════════════════════════════════════╝
  180.  
  181.   o  xcompilebitmap compiles your bitmap into native code which